home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 42 / Amiga Format AFCD42 (Issue 126, Aug 1999).iso / -serious- / programming / other / ioblixdevkit / autodocs / ioblixser.doc < prev   
Text File  |  1999-05-14  |  23KB  |  594 lines

  1.  
  2. TABLE OF CONTENTS
  3.  
  4. ioblixser.device/AbortIO
  5. ioblixser.device/BeginIO
  6. ioblixser.device/CloseDevice
  7. ioblixser.device/CMD_CLEAR
  8. ioblixser.device/CMD_FLUSH
  9. ioblixser.device/CMD_READ
  10. ioblixser.device/CMD_RESET
  11. ioblixser.device/CMD_START
  12. ioblixser.device/CMD_STOP
  13. ioblixser.device/CMD_WRITE
  14. ioblixser.device/GetChipInfo
  15. ioblixser.device/OpenDevice
  16. ioblixser.device/SDCMD_BREAK
  17. ioblixser.device/SDCMD_QUERY
  18. ioblixser.device/SDCMD_SETPARAMS
  19. ioblixser.device/SIOCMD_SETCTRLLINES
  20.  
  21.  
  22. ioblixser.device/AbortIO                               ioblixser.device/AbortIO
  23.  
  24.    NAME
  25.        AbortIO(ioRequest) -- abort an I/O request
  26.                A1
  27.  
  28.    FUNCTION
  29.       This is an exec.library call.
  30.  
  31.       This function attempts to aborts a specified read or write request.
  32.       If the request is active, it is stopped immediately. If the request is
  33.       queued, it is painlessly removed.  The request will be returned
  34.       in the same way any completed request it.
  35.  
  36.       After AbortIO(), you must generally do a WaitIO().
  37.  
  38.    INPUTS
  39.       IORequest  -- pointer to the IORequest Block that is to be aborted.
  40.  
  41.    RESULTS
  42.        io_Error -- if the Abort succeded, then io_Error will be #IOERR_ABORTED
  43.  
  44.            (-2) and the request will be flagged as aborted (bit 5 of 
  45.            io_Flags is set).  If the Abort failed, then the Error will be zero.
  46.  
  47.  
  48. ioblixser.device/BeginIO                               ioblixser.device/BeginIO
  49.  
  50.    NAME
  51.        BeginIO(ioRequest),deviceNode -- start up an I/O process
  52.                 A1        A6
  53.    FUNCTION
  54.        This is a direct function call to the device.  It is intended for
  55.        more advanced programmers.  See exec's DoIO() and SendIO() for
  56.        the normal method of calling devices.
  57.  
  58.        This function initiates a I/O request made to the serial
  59.        device. Other than read or write, the functions are performed 
  60.        synchronously, and do not depend on any interrupt handling 
  61.        logic (or it's associated discontinuities), and hence should
  62.        be performed as IO_QUICK.
  63.        With some exceptions, reads and writes are merely initiated by 
  64.        BeginIO, and thusly return to the caller as begun, not completed.
  65.        Completion is signalled via the standard ReplyMsg routine.
  66.        Multiple requests are handled via FIFO queueing.
  67.        One exception to this non-QUICK handling of reads and writes
  68.        is for READS when:
  69.          - IO_QUICK bit is set
  70.          - There are no pending read requests
  71.          - There is already enough data in the input buffer to satisfy
  72.            this I/O Request immediately.
  73.        In this case, the IO_QUICK flag is not cleared, and the request
  74.        is completed by the time it returns to the caller. There is no
  75.        ReplyMsg or signal bit activity in this case.
  76.           
  77.    INPUTS
  78.        ioRequest  -- pointer to an I/O Request Block of size 
  79.            io_ExtSerSize (see serial.i for size/definition), 
  80.            containing a valid command in io_Command to process,
  81.            as well as the command's other required parameters.
  82.        deviceNode -- pointer to the "ioblixser.device", as found in
  83.            the IO_DEVICE of the ioRequest.
  84.  
  85.    RESULTS
  86.        io_Error -- if the BeginIO succeded, then Error will be null.
  87.            If the BeginIO failed, then the Error will be non-zero.
  88.            I/O errors won't be reported until the io completes.
  89.  
  90.    SEE ALSO
  91.         devices/serial.h
  92.  
  93.  
  94. ioblixser.device/CloseDevice                       ioblixser.device/CloseDevice
  95.  
  96.    NAME
  97.        CloseDevice -- close the serial port
  98.  
  99.    SYNOPSIS
  100.        CloseDevice(deviceNode)
  101.                     A1
  102.    FUNCTION
  103.        This is an exec call that terminates communication with the
  104.        serial device.  Upon closing, the device's input buffer is freed.
  105.  
  106.        Note that all IORequests MUST be complete before closing.
  107.         If any are pending, your program must AbortIO() then WaitIO()
  108.        to complete them.
  109.  
  110.    INPUTS
  111.        deviceNode - pointer to the device node, set by Open
  112.  
  113.    SEE ALSO
  114.        ioblixser.device/OpenDevice
  115.  
  116.  
  117. ioblixser.device/CMD_CLEAR                           ioblixser.device/CMD_CLEAR
  118.  
  119.    NAME
  120.        Clear -- clear the serial port buffers
  121.  
  122.    FUNCTION
  123.        This command resets the serial port's read buffer pointers.
  124.  
  125.    IO REQUEST
  126.        io_Message      mn_ReplyPort initialized
  127.        io_Device       set by OpenDevice
  128.        io_Unit         set by OpenDevice
  129.        io_Command      CMD_CLEAR
  130.  
  131.    RESULTS
  132.        Error -- If the Clear succeded, then io_Error will be null.
  133.                 If the Clear failed, then the io_Error will be non-zero.
  134.  
  135.  
  136. ioblixser.device/CMD_FLUSH                           ioblixser.device/CMD_FLUSH
  137.  
  138.    NAME
  139.        Flush -- clear all queued I/O requests for the serial port
  140.  
  141.    FUNCTION
  142.        This command purges the read and write request queues for the
  143.        serial device. Flush will not affect active requests.
  144.  
  145.    IO REQUEST
  146.        io_Message      mn_ReplyPort initialized
  147.        io_Device       set by OpenDevice
  148.        io_Unit         set by OpenDevice
  149.        io_Command      CMD_FLUSH
  150.  
  151.    RESULTS
  152.        Error -- if the Flush succeded, then io_Error will be null.
  153.                  If the Flush failed, then the io_Error will be non-zero.
  154.  
  155.  
  156. ioblixser.device/CMD_READ                             ioblixser.device/CMD_READ
  157.  
  158.    NAME
  159.        Read -- read input from serial port
  160.  
  161.    FUNCTION
  162.         This command causes a stream of characters to be read in from
  163.         the serial port buffer.  The number of characters is specified
  164.         in io_Length.
  165.  
  166.         The Query function can be used to check how many characters
  167.         are currently waiting in the serial port buffer.  If more characters
  168.         are requested than are currently available, the ioRequest
  169.         will be queued until it can be satisfied.
  170.  
  171.  
  172.         The best way to handle reads is to first Query to get the number
  173.         of characters currently in the buffer.  Then post a read request
  174.         for that number of characters (or the maximum size of your buffer).
  175.  
  176.         If zero characters are in the buffer, post a request
  177.         for 1 character.  When at least one is ready, the device will return
  178.         it.  Now start over with another Query.
  179.  
  180.         Before the program exits, it must be sure to AbortIO() then WaitIO()
  181.         any outstanding ioRequests.
  182.  
  183.    IO REQUEST
  184.        io_Message      A mn_ReplyPort is required
  185.        io_Device       set by OpenDevice
  186.        io_Unit         set by OpenDevice
  187.        io_Command      CMD_READ
  188.        io_Flags        If the IOB_QUICK bit is set, read will try
  189.                         to complete the IO quickly
  190.        io_Length       number of characters to receive.
  191.        io_Data         pointer to buffer
  192.  
  193.    RESULTS
  194.        Error -- if the Read succeded, then io_Error will be null.
  195.            If the Read failed, then io_Error will be non-zero.
  196.              io_Error will indicate problems such as parity mismatch,
  197.              break, and buffer overrun.
  198.  
  199.    SEE ALSO
  200.         ioblixser.device/SDCMD_QUERY
  201.         ioblixser.device/SDCMD_SETPARAMS
  202.  
  203.    BUGS
  204.         Having multiple outstanding read IORequests at any one time will
  205.         probably fail.
  206.  
  207.         Old documentation mentioned a mode where io_Length was set to -1.
  208.         If you want a NULL terminated read, use the io_TermArray instead.
  209.  
  210.  
  211. ioblixser.device/CMD_RESET                           ioblixser.device/CMD_RESET
  212.  
  213.    NAME
  214.        Reset -- reinitializes the serial port
  215.  
  216.    FUNCTION
  217.        This command resets the serial port to its freshly initialized
  218.        condition. It aborts all I/O requests both queued and current,
  219.        relinquishes the current buffer, obtains a new default sized
  220.        buffer, and sets the port's flags and parameters to their 
  221.        boot-up time default values. The functions places the reset
  222.        parameter values in the ioRequest block.
  223.  
  224.    IO REQUEST
  225.        io_Message      mn_ReplyPort initialized
  226.        io_Device       set by OpenDevice
  227.        io_Unit         set by OpenDevice
  228.        io_Command      CMD_RESET
  229.  
  230.    RESULTS
  231.        Error -- if the Reset succeded, then Error will be null.
  232.            If the Reset failed, then the Error will be non-zero.
  233.  
  234.  
  235. ioblixser.device/CMD_START